home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / NEWSOFT / AUGUST / FREENET2 / !FreeNet / Docs / SWIs < prev    next >
Text File  |  1996-10-19  |  28KB  |  716 lines
  1.           The Programmer Interface to the FreeNet TCP/IP Stack
  2.  
  3.                           (C) Tom Hughes 1995
  4.  
  5. 0. Copyright
  6.  
  7.   The FreeNet module and application and the tools and documentation
  8.   that go with them are all copyright. They are however released as
  9.   freeware subject to certain terms and conditions. These are described
  10.   in the file named 'Licence' which should have accompanied this
  11.   document.
  12.  
  13. 1. Overview
  14.  
  15.   The FreeNet TCP/IP Stack provides the same interface to the programmer
  16.   that the Acorn TCP/IP stack does, namely a BSD sockets interface
  17.   provided via SWI calls. There is also a library of AOF object files
  18.   available that provides a BSD sockets interface to these calls for use
  19.   by C programmers.
  20.  
  21.   There is a one to one mapping between the SWI calls provided by the
  22.   FreeNet stack, and the normal BSD socket calls. The arguments are
  23.   passed in order starting with register 0 and working up, with the
  24.   return value being passed back in R0.
  25.  
  26.   The only difference is that errors are signaled by returning a RISC OS
  27.   error in the normal way (with V set and R0 pointing to an error block)
  28.   instead of by returning a value of -1. The error number in the error
  29.   block will be a normal Unix error code however, and the C library
  30.   veneers convert these errors back into a -1 return code with errno
  31.   set.
  32.  
  33.   The mapping between BSD calls and SWI calls is decribed by the
  34.   following table:
  35.  
  36.          SWI Number    SWI Name                BSD Call
  37.  
  38.            &41200      Socket_Creat            socket()
  39.            &41201      Socket_Bind             bind()
  40.            &41202      Socket_Listen           listen()
  41.            &41203      Socket_Accept           accept()
  42.            &41204      Socket_Connect          connect()
  43.            &41205      Socket_Recv             recv()
  44.            &41206      Socket_Recvfrom         recvfrom()
  45.            &41207      Socket_Recvmsg          recvmsg()
  46.            &41208      Socket_Send             send()
  47.            &41209      Socket_Sendto           sendto()
  48.            &4120A      Socket_Sendmsg          sendmsg()
  49.            &4120B      Socket_Shutdown         shutdown()
  50.            &4120C      Socket_Setsockopt       setsockopt()
  51.            &4120D      Socket_Getsockopt       getsockopt()
  52.            &4120E      Socket_Getpeername      getpeername()
  53.            &4120F      Socket_Getsockname      getsockname()
  54.            &41210      Socket_Close            close()
  55.            &41211      Socket_Select           select()
  56.            &41212      Socket_Ioctl            ioctl()
  57.            &41213      Socket_Read             read()
  58.            &41214      Socket_Write            write()
  59.            &41215      Socket_Stat             stat()
  60.            &41216      Socket_Readv            readv()
  61.            &41217      Socket_Writev           writev()
  62.            &41218      Socket_Gettsize         FD_SETSIZE
  63.            &41219      Socket_Sendtosm         ?
  64.  
  65.   The remainder of this document details each of these SWIs in full,
  66.   describing the arguments and possible return values.
  67.  
  68. 2. Error Codes
  69.  
  70.   The errors returned by the Socket SWIs are normal RISC OS errors,
  71.   complete with suitable explanatory text. The error number will be a
  72.   Unix error code. These numbers (and the sybolic names associated with
  73.   them) are as follows:
  74.  
  75.        Name            Number    Explanation
  76.  
  77.        EINTR              4      Interrupted system call
  78.        ENXIO              6      Device not configured
  79.        EBADF              9      Bad descriptor
  80.        ENOMEM            12      Cannot allocate memory
  81.        EACCES            13      Permission denied
  82.        EFAULT            14      Bad address
  83.        EINVAL            22      Invalid argument
  84.        EMFILE            24      Too many open files
  85.        EPIPE             32      Broken pipe
  86.        EWOULDBLOCK       35      Operation would block
  87.        EINPROGRESS       36      Operation now in progress
  88.        EALREADY          37      Operation already in progress
  89.        EDESTADDRREQ      39      Destination address required
  90.        EMSGSIZE          40      Message too long
  91.        ENOPROTOOPT       42      Protocol not available
  92.        EPROTONOSUPPORT   43      Protocol not supported
  93.        ESOCKTNOSUPPORT   44      Socket type not supported
  94.        EOPNOTSUPP        45      Operation not supported
  95.        EPFNOSUPPORT      46      Protocol family not supported
  96.        EAFNOSUPPORT      47      Address family not supported
  97.        EADDRINUSE        48      Address already in use
  98.        EADDRNOTAVAIL     49      Can't assign requested address
  99.        ENETDOWN          50      Network is down
  100.        ENETUNREACH       51      Network is unreachable
  101.        ECONNABORTED      53      Software caused connection abort
  102.        ECONNRESET        54      Connection reset by peer
  103.        ENOBUFS           55      No buffer space available
  104.        EISCONN           56      Socket is already connected
  105.        ENOTCONN          57      Socket is not connected
  106.        ETIMEDOUT         60      Operation timed out
  107.        ECONNREFUSED      61      Connection refused
  108.        EHOSTUNREACH      64      Host is down
  109.        EHOSTUNREACH      65      No route to host
  110.  
  111.   Throughout the rest of this document, the symbolic names referred to
  112.   above will be used when talking about specific errors.
  113.  
  114. 3. Other Symbolic Constants
  115.  
  116.   Various other constants are used as arguments to Socket SWIs, and these
  117.   are referred to in this document by the symbolic names used for them
  118.   in the BSD library code. Their values are as follows:
  119.  
  120.        Name            Value           Name            Value
  121.  
  122.        SOCK_STREAM       1             SO_DEBUG           &0001
  123.        SOCK_DGRAM        2             SO_ACCEPTCONN      &0002
  124.        SOCK_RAW          3             SO_REUSEADDR       &0004
  125.                                        SO_KEEPALIVE       &0008
  126.        PF_INET           2             SO_DONTROUTE       &0010
  127.                                        SO_BROADCAST       &0020
  128.        AF_INET           2             SO_LINGER          &0080
  129.                                        SO_OOBINLINE       &0100
  130.        MSG_OOB          &01            SO_SNDBUF          &1001
  131.        MSG_PEEK         &02            SO_RCVBUF          &1002
  132.        MSG_EOR          &08            SO_SNDLOWAT        &1003
  133.        MSG_TRUNC        &10            SO_RCVLOWAT        &1004
  134.        MSG_WAITALL      &40            SO_SNDTIMEO        &1005
  135.        MSG_DONTWAIT     &80            SO_RCVTIMEO        &1006
  136.                                        SO_ERROR           &1007
  137.        SOL_SOCKET      &FFFF           SO_TYPE            &1008
  138.                                        
  139.        IP_OPTIONS        1             SIOCSIFADDR      &8020690C
  140.        IP_HDRINCL        2             OSIOCGIFADDR     &C020690D
  141.        IP_TOS            3             SIOCGIFADDR      &C0206921
  142.        IP_TTL            4             SIOCSIFDSTADDR   &8020690E
  143.                                        OSIOCGIFDSTADDR  &C020690F
  144.        TCP_NODELAY       1             SIOCGIFDSTADDR   &C0206922
  145.        TCP_MAXSEG        2             SIOCSIFFLAGS     &80206910
  146.                                        SIOCGIFFLAGS     &C0206911
  147.        FIOSLEEPTW    &80046679         OSIOCGIFBRDADDR  &C0206912
  148.        FIOASYNC      &8004667D         SIOCGIFBRDADDR   &C0206923
  149.        FIONBIO       &8004667E         SIOCSIFBRDADDR   &80206913
  150.        FIONREAD      &4004667F         OSIOCGIFCONF     &C0206914
  151.                                        SIOCGIFCONF      &C0206924
  152.        SIOCATMARK    &80047307         OSIOCGIFNETMASK  &C0206915
  153.                                        SIOCGIFNETMASK   &C0206925
  154.                                        SIOCSIFNETMASK   &80206916
  155.                                        SIOCGIFMETRIC    &C0206917
  156.                                        SIOCSIFMETRIC    &80206918
  157.                                        SIOCDIFADDR      &80206919
  158.                                        SIOCAIFADDR      &80206920
  159.  
  160. 4. Socket_Creat
  161.  
  162.   In: R0 = Protocol family
  163.       R1 = Socket type
  164.       R2 = Protocol
  165.  
  166.   Out: R0 = Socket descriptor
  167.  
  168.   This call creates a new socket of a given type and using a given
  169.   protocol.  If the protocol is left unspecified (passed as zero), a
  170.   default applicable to that socket type will be used.
  171.  
  172.   The internet protocol family (PF_INET) is the only one supported by this
  173.   module. Three socket type are supported:
  174.  
  175.     SOCK_STREAM - Stream orientated connections providing bi-directional
  176.                   sequenced, reliable transfer of byte streams. The only
  177.                   protocol of this type currently supported is the
  178.                   transmission control protocol (TCP).
  179.  
  180.     SOCK_DGRAM  - Connectionless, messages based protocols providing
  181.                   unreliable, non-sequence communication. The only
  182.                   protocol of this type currently supported is the user
  183.                   datagram protocol (UDP).
  184.  
  185.     SOCK_RAW    - Low level access to the underlying packet based
  186.                   transport mechanism to allow the implementation of
  187.                   alternative higher level protocols.
  188.  
  189.   Note that this call will not give the socket an address, or connect it
  190.   to any remote address. The socket can be given an address explicitly
  191.   using the Socket_Bind call, or it will be assigned one automatically
  192.   when it is first used to send data or to connect to a remote address.
  193.  
  194. 5. Socket_Bind
  195.  
  196.   In: R0 = Socket descriptor
  197.       R1 = Pointer to local address to bind socket to
  198.       R2 = Size of local address
  199.  
  200.   Out: R0 corrupted
  201.  
  202.   This call binds a socket to a specified local address. The format of
  203.   the address (for Internet addresses) is:
  204.  
  205.     R1 + 0 = Address family
  206.          2 = Port number
  207.          4 = IP address
  208.          8 = Reserved (should be zero)
  209.  
  210.   The address family is always AF_INET for internet addresses. The
  211.   reserved portion of the address can be omitted, provided that the
  212.   address size is passed correctly to indicate this.
  213.  
  214.   Note that the port number and IP address need to be in network byte
  215.   order, which is the reverse of the normal byte order on all current
  216.   Acorn machines.
  217.  
  218. 6. Socket_Listen
  219.  
  220.   In: R0 = Socket descriptor
  221.       R1 = Maximum backlog
  222.  
  223.   Out: R0 corrupted
  224.  
  225.   This call causes a socket of type SOCK_STREAM to begin listening for
  226.   incoming connection attempts. The backlog parameter specifies the
  227.   maximum length that the queue of pending connections may grow to
  228.   before connection attempts will be refused.
  229.  
  230. 7. Socket_Accept
  231.  
  232.   In: R0 = Socket descriptor of listening socket
  233.       R1 = Pointer to address to be filled in
  234.       R2 = Pointer to word giving the size of the address block
  235.  
  236.   Out: R0 = Socket descriptor for new connection
  237.  
  238.   This call is used to accept connections from server sockets that have
  239.   been told to listen for new connections. A new socket will be created
  240.   for each incoming connection, and this call in then used to obtain the
  241.   descriptor for the next pending connection.
  242.  
  243.   The address of the host which initiated the returned connection will
  244.   also be returned, in the supplied address block. This block is in the
  245.   same format as that given to Socket_Bind.
  246.  
  247.   If there are no connections waiting to be accepted, this call will
  248.   block until a connection is available to be returned, unless the
  249.   socket has been marked as non-blocking using Socket_Ioctl, in which
  250.   case the error EWOULDBLOCK will be returned.
  251.  
  252. 8. Socket_Connect
  253.  
  254.   In: R0 = Socket descriptor
  255.       R1 = Pointer to address of remote host
  256.       R2 = Size of supplied address block
  257.  
  258.   Out: R0 corrupted
  259.  
  260.   This call initiates a connection from the specified socket to a given
  261.   address on another host. When used on a raw or datagram socket, this
  262.   will simply fix the remote address for future calls to Socket_Send,
  263.   and this remote address can be changed by calling this routine again.
  264.  
  265.   For stream sockets, FreeNet will attempt to make a connection to the
  266.   specified address, and will block until the connection is achieved or
  267.   the attempt fails. If the socket has been marked non-blocking it will
  268.   instead return immediately with the error EINPROGRESS and will continue
  269.   with the connection attempt on its own.
  270.  
  271. 9. Socket_Recv
  272.  
  273.   In: R0 = Socket descriptor
  274.       R1 = Pointer to buffer for received data
  275.       R2 = Size of buffer
  276.       R3 = Flags
  277.  
  278.   Out: R0 = Amount of data received
  279.  
  280.   This call reads as much data as possible from the specified socket, and
  281.   returns it in the supplied buffer. If no data is available, the call
  282.   will block until data is available, unless the socket has been marked
  283.   non-blocking, in which case EWOULDBLOCK will be returned.
  284.  
  285.   Various bits in the flags word can be set to affect how how the read
  286.   is performed:
  287.  
  288.     MSG_PEEK     - Just peek at the data, leaving it in place to be
  289.                       read by a subsequent call.
  290.  
  291.     MSG_OOB      - Read any out-of-band data that is waiting on the
  292.                       socket, in place of the normal data.
  293.  
  294.     MSG_DONTWAIT - Treat this particular call as non-blocking, ignoring
  295.                    the sockets normal blocking/non-blocking status.
  296.  
  297.     MSG_WAITALL  - Try and completely fill the supplied buffer, blocking
  298.                    for more data if necessary.
  299.  
  300.   For stream sockets, this call may return zero as an indication that the
  301.   other end has closed the connection.
  302.  
  303. 10. Socket_Recvfrom
  304.  
  305.   In: R0 = Socket descriptor
  306.       R1 = Pointer to buffer for received data
  307.       R2 = Size of buffer
  308.       R3 = Flags
  309.       R4 = Pointer to address to be filled in
  310.       R5 = Pointer to word giving the size of the address block
  311.  
  312.   Out: R0 = Amount of data received
  313.  
  314.   This call has identical functionality to Socket_Recv except that the
  315.   address of the host that sent the data will be returned in the block
  316.   supplied, in the same format as used by Socket_Bind.
  317.  
  318. 11. Socket_Recvmsg
  319.  
  320.   In: R0 = Socket descriptor
  321.       R1 = Pointer to message descriptor
  322.       R2 = Flags
  323.  
  324.   Out: R0 = Amount of data received
  325.  
  326.   This call behaves in the same way as Socket_Recvfrom, except that the
  327.   message descriptor is used to indicate where the address should be
  328.   placed and to give a list of buffers to return the data in. The format
  329.   of the message descriptor is:
  330.  
  331.     R1 + 0  = Pointer to address to be filled in
  332.        + 4  = Size of supplied address block
  333.        + 8  = Pointer to array of buffer descriptors
  334.        + 12 = Number of buffer descriptors in use
  335.        + 16 = Pointer to list of access rights (unused by FreeNet)
  336.        + 20 = Size of access rights list
  337.        + 24 = Flags for received data
  338.  
  339.   Each buffer descriptor consists of two words. The first is a pointer
  340.   to the buffer, and the second the size of the buffer. The flags which
  341.   can be returned in the message descriptor are:
  342.   
  343.     MSG_TRUNC - Message was truncated.
  344.     
  345.     MSG_EOR   - This data completes a record.
  346.  
  347. 12. Socket_Send
  348.  
  349.   In: R0 = Socket descriptor
  350.       R1 = Pointer to data to be sent
  351.       R2 = Size of buffer
  352.       R3 = Flags
  353.  
  354.   Out: R0 = Amount of data sent
  355.  
  356.   This call sends data on a socket. In the case of datagram and raw sockets,
  357.   a single datagram containing the data will be sent, and EMSGSIZE will be
  358.   returned if the data is too large to be sent in this way. For stream
  359.   sockets, the call will block until all the data has been sent, unless
  360.   the socket has been marked non-blocking, in which case as much data as
  361.   possible will be sent.
  362.  
  363.   Various bits in the flags word can be set to affect how how the send is
  364.   performed:
  365.  
  366.     MSG_OOB      - Send data as out-of-band data instead of normal
  367.                     in-band data.
  368.  
  369.   Because this call does not specify the address to send to, the socket
  370.   used for this call must be a connected socket.
  371.  
  372. 13. Socket_Sendto
  373.  
  374.   In: R0 = Socket descriptor
  375.       R1 = Pointer to data to be sent
  376.       R2 = Size of buffer
  377.       R3 = Flags
  378.       R4 = Pointer to address to send to
  379.       R5 = Size of supplied address block
  380.  
  381.   Out: R0 = Amount of data sent
  382.  
  383.   This call performs the same job as Socket_Send, except that the remote
  384.   address is specified so that it can be used on unconnected sockets. This
  385.   call is only useful for sockets that do not require a connection such
  386.   as those using the UDP protocol. For sockets that require a connection
  387.   such as those using the TCP protocol, you need to call Socket_Connect
  388.   before you can use this routine, and the address given to this call
  389.   is then ignored anyway.
  390.  
  391. 14. Socket_Sendmsg
  392.  
  393.   In: R0 = Socket descriptor
  394.       R1 = Pointer to message descriptor
  395.       R2 = Flags
  396.  
  397.   Out: R0 = Amount of data sent
  398.  
  399.   This call behaves in the same way as Socket_Sendto, except that the
  400.   message descriptor is used to indicate where the address should be
  401.   taken from and to give a list of buffers containing the data in. The
  402.   format of the message descriptor is as given for Socket_Recvmsg.
  403.  
  404. 15. Socket_Shutdown
  405.  
  406.   In: R0 = Socket descriptor
  407.       R1 = Direction of shutdown
  408.  
  409.   Out: R0 corrupted
  410.  
  411.   Perform a half close on a stream socket. This call is able to shut
  412.   down either the send or received side of the socket, or both. The
  413.   direction parameter is either 0 to shut down the receive side, 1 to
  414.   shut down the send side, or 2 to shut down both sides of the socket.
  415.  
  416. 16. Socket_Setsockopt
  417.  
  418.   In: R0 = Socket descriptor
  419.       R1 = Option level
  420.       R2 = Option
  421.       R3 = Pointer to option value
  422.       R4 = Size of option value
  423.  
  424.   Out: R0 corrupted
  425.  
  426.   This is used to set a particular option on a socket. The level is
  427.   either SOL_SOCKET for options applicable to all sockets, or a protocol
  428.   number for options applicable to a certain protocol. Currently
  429.   supported socket level options are:
  430.  
  431.     SO_REUSEADDR - Enables or disables the reuse of local addresses
  432.                    during the wait period that normally occurs when
  433.                    a TCP stream socket is closed. The argument is a
  434.                    single word which contains zero to disable this
  435.                    option, or a non-zero value to enable it.
  436.  
  437.     SO_KEEPALIVE - Enable or disable attempts by FreeNet to probe the
  438.                    remote end of a TCP connection when the link has
  439.                    been idle for some time.
  440.  
  441.     SO_BROADCAST - Enable or disable sending of broadcast packets
  442.                    through this socket.
  443.  
  444.     SO_LINGER    - Control whether the socket lingers on close. The
  445.                    argument points to two words, the first of which
  446.                    is a boolean that indicates wether the socket waits
  447.                    for data to drain when it is closed, and the
  448.                    second is the length of time to wait in seconds.
  449.  
  450.     SO_OOBINLINE - Control whether OOB data is received inline with
  451.                    the normal data, or out of line as a separate data
  452.                    stream.
  453.  
  454.     SO_SNDBUF    - Set the size of the send buffer to the value given
  455.                    by the argument, which is a single word.
  456.  
  457.     SO_RCVBUF    - Set the size of the receive buffer to the value given
  458.                    by the argument, which is a single word.
  459.  
  460.     SO_SNDLOWAT  - Set the low water mark of the send buffer. The stack
  461.                    will block a send until there is this much space in
  462.                    the send buffer before it starts to send the data.
  463.  
  464.     SO_RCVLOWAT  - Set the low water mark of the receive buffer. The
  465.                    stack will always try and return at least this many
  466.                    bytes on a read, blocking if necessary.
  467.  
  468.     SO_SNDTIMEO  - Set the send timeout. This is the maximum length
  469.                    of time that a send call will block for before
  470.                    returning. The argument is a pointer to a timeout
  471.                    block as described under Socket_Select.
  472.  
  473.     SO_RCVTIMEO  - Set the receive timeout. This is the maximum length
  474.                    of time that a receive call will block for before
  475.                    returning. The argument is a pointer to a timeout
  476.                    block as described under Socket_Select.
  477.  
  478.   The IP protocol also supports several options:
  479.  
  480.     IP_OPTIONS   - Set some IP options which will be added to each
  481.                    packet sent on a socket.
  482.  
  483.     IP_HDRINCL   - This toggles whether data sent on a socket already
  484.                    has an IP header included or not. This should only
  485.                    ever be set on raw sockets.
  486.  
  487.     IP_TOS       - Set the type of service field in packets sent using
  488.                    this socket to the specified value.
  489.  
  490.     IP_TTL       - Set the time to live field in packets sent using
  491.                    this socket to the specified value.
  492.  
  493.   Finally, there are a number of options supported by the TCP protocol:
  494.  
  495.     TCP_NODELAY - Disable the Nagle algorithm for this connection, to
  496.                   ensure that data is always sent immediately.
  497.  
  498.     TCP_MAXSEG  - Set the maximum segment size to use for data sent on
  499.                   this connection.
  500.  
  501. 16. Socket_Getsockopt
  502.  
  503.   In: R0 = Socket descriptor
  504.       R1 = Option level
  505.       R2 = Option
  506.       R3 = Pointer to buffer for option value
  507.       R4 = Size of option value buffer
  508.  
  509.   Out: R0 corrupted
  510.  
  511.   This call can be used to read the current value of any of the options
  512.   set using Socket_Setsockopt. In addition, there are two more socket
  513.   level options that can be read but not written:
  514.  
  515.     SO_ERROR - Return the Unix error code for any error which has
  516.                occurred on the socket, and clear the sockets error
  517.                flag.
  518.  
  519.     SO_TYPE  - Return the socket type set when the socket was
  520.                created.
  521.  
  522. 17. Socket_Getpeername
  523.  
  524.   In: R0 = Socket descriptor
  525.       R1 = Pointer to address to be filled in
  526.       R2 = Pointer to word giving the size of the address block
  527.  
  528.   Out: R0 corrupted
  529.  
  530.   This call returns the address that the socket is connected to (if any)
  531.   in the supplied address block.
  532.  
  533. 18. Socket_Getsockname
  534.  
  535.   In: R0 = Socket descriptor
  536.       R1 = Pointer to address to be filled in
  537.       R2 = Pointer to word giving the size of the address block
  538.  
  539.   Out: R0 corrupted
  540.  
  541.   This call returns the local address that the socket is bound to (if
  542.   any) in the supplied address block.
  543.  
  544. 19. Socket_Close
  545.  
  546.   In: R0 = Socket descriptor
  547.   
  548.   Out: R0 corrupted
  549.  
  550.   Close a socket, freeing the descriptor for reuse. For stream sockets,
  551.   this is roughly equivalent to calling Socket_Shutdown with a type code
  552.   of 2, whilst for datagram sockets this call immediately deletes the
  553.   socket.
  554.  
  555. 20. Socket_Select
  556.  
  557.   In: R0 = Number of descriptors to consider in each set
  558.       R1 = Pointer to read descriptor set
  559.       R2 = Pointer to write descriptor set
  560.       R3 = Pointer to exception descriptor set
  561.       R4 = Pointer to timeout block
  562.  
  563.   Out: Number of ready descriptors
  564.  
  565.   This call polls a specified groups of sockets to see which are ready
  566.   for reading, which are ready for writing and which had exceptional
  567.   conditions pending.
  568.  
  569.   Each of the three descriptor sets is a bitmask, where bit zero refers
  570.   to socket zero, bit one to socket one and so on. Only those sockets
  571.   whose bit is set in a mask will be considered when performing the
  572.   checks. As FreeNet currently supports 128 sockets, the bitmasks are
  573.   arrays of four words - descriptors 0 to 31 are in the first word and
  574.   so on.
  575.  
  576.   The value in R0 is the number of bits in the descriptor sets which
  577.   should be considered as having meaning, so if R0 is 9 only the
  578.   first 9 bits (descriptors 0 to 8) will be considered.
  579.  
  580.   This call will return as soon as one or more of the sockets being
  581.   tested is ready or when a timeout occurs. Passing a null pointer
  582.   for the timeout means the call will never timeout, and will block
  583.   until a socket is ready. The timeout takes the following form:
  584.  
  585.     R4 + 0 = Number of seconds to wait
  586.          4 = Number of microseconds to wait
  587.  
  588.   A timeout with both fields set to zero will cause the call to return
  589.   immediately, regardless of how many sockets are ready.
  590.  
  591. 21. Socket_Ioctl
  592.  
  593.   In: R0 = Socket descriptor
  594.       R1 = Operation
  595.       R2 = Pointer to argument
  596.  
  597.   Out: R0 corrupted
  598.  
  599.   This call is used to perform miscellaneous control operations on
  600.   individual sockets and on the TCP/IP stack as a whole. At the moment,
  601.   these operations are supported:
  602.  
  603.     FIOSLEEPTW - Mark a socket as using OS_Upcall 6 to allow multitasking
  604.                  to continue during blocking socket calls made from a
  605.                  taskwindow.
  606.  
  607.     FIOASYNC   - Mark a socket for asynchronous operation. This means that
  608.                  a RISC OS event will be raised when important changes
  609.                  occur in the sockets status. See the section on events
  610.                  for more detail of the events that are raised. The argument
  611.                  is a single word acting as a boolean flag.
  612.  
  613.     FIONBIO    - Mark a socket non-blocking so that no attempted operations
  614.                  on the socket will block. They will instead fail with the
  615.                  error EWOULDBLOCK if they are unable to complete straight
  616.                  away. The argument is a single word acting as a boolean
  617.                  flag.
  618.  
  619.     FIONREAD   - Read the number of bytes available for reading from the
  620.                  socket. The argument is an integer which will be filled in
  621.                  with the number of bytes available.
  622.  
  623.     SIOCATMARK - Read a boolean indicator that says whether we are at
  624.                  the OOB marker in the data stream.
  625.  
  626.   This call also supports certain operations on the interface table, but
  627.   details of this are outside the current scope of this document. Future
  628.   extensions will implement the remaining operations on the routing table
  629.   and also a set of operations on the routing tables.
  630.  
  631. 22. Socket_Read
  632.  
  633.   In: R0 = Socket descriptor
  634.       R1 = Pointer to buffer for received data
  635.       R2 = Size of buffer
  636.  
  637.   Out: R0 = Amount of data received
  638.  
  639.   This call reads data from a socket in the same style as Socket_Recv
  640.   except that there is no flags argument, so all flags are treated as
  641.   being zero.
  642.  
  643. 23. Socket_Write
  644.  
  645.   In: R0 = Socket descriptor
  646.       R1 = Pointer to data to be sent
  647.       R2 = Size of buffer
  648.  
  649.   Out: R0 = Amount of data sent
  650.  
  651.   This call sends data on a socket in the same style as Socket_Send
  652.   except that there is no flags argument, so all flags are treated as
  653.   being zero.
  654.  
  655. 24. Socket_Stat
  656.  
  657.   This call is not supported by FreeNet yet.
  658.  
  659. 25. Socket_Readv
  660.  
  661.   In: R0 = Socket descriptor
  662.       R1 = Pointer to array of buffer descriptors
  663.       R2 = Number of buffer descriptors
  664.  
  665.   Out: R0 = Amount of data received
  666.  
  667.   This call reads data into a gather array. The buffer descriptors are
  668.   the same as those described for Socket_Recvmsg, and as with Socket_Read
  669.   the flags are all treated as being zero.
  670.  
  671. 25. Socket_Writev
  672.  
  673.   In: R0 = Socket descriptor
  674.       R1 = Pointer to array of buffer descriptors
  675.       R2 = Number of buffer descriptors
  676.  
  677.   Out: R0 = Amount of data sent
  678.  
  679.   This call sends data from a scatter array. The buffer descriptors are
  680.   the same as those described for Socket_Recvmsg, and as with Socket_Write
  681.   the flags are all treated as being zero.
  682.  
  683. 26. Socket_Gettsize
  684.  
  685.   In: Nothing
  686.  
  687.   Out: R0 = Number of descriptors available
  688.  
  689.   This call returns the number of descriptors available to the caller,
  690.   including those currently in use.
  691.  
  692. 27. Socket_Sendtosm
  693.  
  694.   This call is not supported by FreeNet yet.
  695.  
  696. 28. The Internet Event
  697.  
  698.   If a socket has been marked for asynchronous operation using Socket_Ioctl
  699.   the TCP/IP stack will raise a RISC OS event (event 19) when important
  700.   changes occur which affect the socket. When the event occurs, registers
  701.   will be set as follows:
  702.  
  703.      R0 = 19
  704.      R1 = Event code
  705.      R2 = Socket descriptor
  706.  
  707.   Where the socket descriptor is the socket affected by the event, and the
  708.   event code is on of the following values:
  709.  
  710.      1   Socket has input waiting to be read
  711.      2   An urgent event has occured (eg arrival of OOB data )
  712.      3   Socket's connection has been broken
  713.  
  714.   This event can be trapped and used to know when to read data from the
  715.   socket, and when a connection has been closed.
  716.